---
title: 트레이싱
description: Learn how to trace your agent runs
---

import { Aside, Code } from '@astrojs/starlight/components';
import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw';
import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw';

Agents SDK에는 에이전트 실행 중 발생하는 이벤트에 대한 포괄적인 기록을 수집하는 기본 트레이싱이 포함되어 있습니다: LLM 생성, 도구 호출, 핸드오프, 가드레일, 그리고 사용자 지정 이벤트까지. [Traces 대시보드](https://platform.openai.com/traces)를 사용해 개발 및 프로덕션에서 워크플로를 디버그, 시각화, 모니터링할 수 있습니다.

<Aside type="note">

트레이싱은 기본적으로 활성화되어 있습니다. 트레이싱을 비활성화하는 방법은 두 가지입니다:

1. 환경 변수 `OPENAI_AGENTS_DISABLE_TRACING=1` 로 전역 비활성화
2. 단일 실행에 대해 [`RunConfig.tracingDisabled`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#tracingdisabled)를 `true` 로 설정

**_OpenAI의 API를 사용하는 Zero Data Retention (ZDR) 정책 하의 조직에서는 트레이싱을 사용할 수 없습니다._**

</Aside>

## 내보내기 루프 라이프사이클

대부분의 환경에서는 트레이스가 정기적으로 자동 내보내기됩니다. 브라우저 또는 Cloudflare Workers에서는 이 기능이 기본적으로 비활성화됩니다. 대기열에 너무 많은 트레이스가 쌓이면 내보내기되지만, 정기적으로 내보내기되지는 않습니다. 대신 코드 라이프사이클의 일부로 `getGlobalTraceProvider().forceFlush()` 를 사용해 수동으로 트레이스를 내보내야 합니다.

예를 들어, Cloudflare Worker에서는 코드를 `try/catch/finally` 블록으로 감싸고, 종료 전에 트레이스가 내보내지도록 `waitUntil` 과 함께 강제 플러시를 사용해야 합니다.

<Code
  lang="typescript"
  code={cloudflareWorkers.replace(/\s+\/\/ @ts-expect-error.*$/m, '')}
  meta="{13}"
/>

## 트레이스와 스팬

- **트레이스(Traces)** 는 하나의 "워크플로"에 대한 단일 엔드 투 엔드 작업을 나타냅니다. 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다:
  - `workflow_name`: 논리적 워크플로 또는 앱 이름입니다. 예: "Code generation", "Customer service"
  - `trace_id`: 트레이스의 고유 ID. 전달하지 않으면 자동 생성됨. 형식은 `trace_<32_alphanumeric>` 이어야 함
  - `group_id`: 선택적 그룹 ID로, 동일한 대화의 여러 트레이스를 연결할 수 있음. 예: 채팅 스레드 ID
  - `disabled`: True이면 트레이스가 기록되지 않음
  - `metadata`: 트레이스에 대한 선택적 메타데이터
- **스팬(Spans)** 은 시작과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 있습니다:
  - `started_at` 및 `ended_at` 타임스탬프
  - 속한 트레이스를 나타내는 `trace_id`
  - 이 스팬의 부모 스팬을 가리키는 `parent_id`(있을 경우)
  - 스팬에 대한 정보인 `span_data`. 예를 들어, `AgentSpanData` 는 에이전트에 관한 정보를, `GenerationSpanData` 는 LLM 생성에 관한 정보를 포함

## 기본 트레이싱

기본적으로 SDK는 다음을 트레이싱합니다:

- 전체 `run()` 또는 `Runner.run()` 이 `Trace` 로 래핑됨
- 에이전트가 실행될 때마다 `AgentSpan` 으로 래핑됨
- LLM 생성은 `GenerationSpan` 으로 래핑됨
- 함수 도구 호출은 각각 `FunctionSpan` 으로 래핑됨
- 가드레일은 `GuardrailSpan` 으로 래핑됨
- 핸드오프는 `HandoffSpan` 으로 래핑됨

기본적으로 트레이스 이름은 "에이전트 워크플로"입니다. `withTrace` 를 사용해서 이 이름을 설정할 수 있으며, [`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) 으로 이름 및 기타 속성을 구성할 수도 있습니다.

또한 [사용자 지정 트레이싱 프로세서](#custom-tracing-processors)를 설정해 다른 대상으로 트레이스를 전송할 수 있습니다(대체 또는 보조 대상으로).

### 음성 에이전트 트레이싱

기본 OpenAI Realtime API와 함께 `RealtimeAgent` 및 `RealtimeSession` 을 사용하는 경우, `RealtimeSession` 에서 `tracingDisabled: true` 로 비활성화하거나 `OPENAI_AGENTS_DISABLE_TRACING` 환경 변수를 사용하지 않는 한 트레이싱은 Realtime API 측에서 자동으로 수행됩니다.

자세한 내용은 [음성 에이전트 개요](/openai-agents-js/ko/guides/voice-agents)를 확인하세요.

## 상위 수준 트레이스

때때로 여러 번의 `run()` 호출을 하나의 트레이스에 포함시키고 싶을 수 있습니다. 전체 코드를 `withTrace()` 로 감싸면 됩니다.

<Code lang="typescript" code={customTraceExample} />

1. 두 번의 `run` 호출이 `withTrace()` 로 감싸져 있으므로, 개별 실행이 두 개의 트레이스를 만들지 않고 전체 트레이스의 일부가 됩니다.

## 트레이스 생성

[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 함수를 사용해 트레이스를 생성할 수 있습니다. 또는 `getGlobalTraceProvider().createTrace()` 로 수동으로 새 트레이스를 생성한 뒤 `withTrace()` 에 전달할 수도 있습니다.

현재 트레이스는 [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) 또는 해당 환경의 폴리필을 통해 추적됩니다. 이는 동시성에서도 자동으로 동작함을 의미합니다.

## 스팬 생성

여러 `create*Span()`(예: `createGenerationSpan()`, `createFunctionSpan()` 등) 메서드를 사용해 스팬을 생성할 수 있습니다. 일반적으로 스팬을 수동으로 만들 필요는 없습니다. 사용자 지정 스팬 정보를 추적하기 위한 [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 함수가 제공됩니다.

스팬은 자동으로 현재 트레이스의 일부가 되며, [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) 또는 해당 환경의 폴리필을 통해 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다.

## 민감한 데이터

일부 스팬은 잠재적으로 민감한 데이터를 캡처할 수 있습니다.

`createGenerationSpan()` 은 LLM 생성의 입력/출력을 저장하고, `createFunctionSpan()` 은 함수 호출의 입력/출력을 저장합니다. 이들에는 민감한 데이터가 포함될 수 있으므로, [`RunConfig.traceIncludeSensitiveData
`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) 를 통해 해당 데이터 캡처를 비활성화할 수 있습니다.

## 사용자 지정 트레이싱 프로세서

트레이싱의 상위 수준 아키텍처는 다음과 같습니다:

- 초기화 시 전역 [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) 를 생성합니다. 이는 트레이스 생성을 담당하며 [`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) 를 통해 접근할 수 있습니다.
- `TraceProvider` 를 [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) 로 구성하여, 배치로 트레이스/스팬을 [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) 에 전송하고, 이는 배치로 OpenAI 백엔드에 스팬과 트레이스를 내보냅니다.

기본 설정을 사용자 지정하여 다른 백엔드로 트레이스를 전송하거나 추가 백엔드를 사용하거나, 익스포터 동작을 변경하려면 다음 두 가지 옵션이 있습니다:

1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) 는 트레이스와 스팬이 준비될 때 이를 수신할 수 있는 **추가** 트레이스 프로세서를 추가할 수 있게 합니다. 이를 통해 OpenAI 백엔드로 트레이스를 보내는 것과 더불어 자체 처리를 수행할 수 있습니다.
2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) 는 기본 프로세서를 사용자 지정 트레이스 프로세서로 **교체** 할 수 있게 합니다. 이 경우 OpenAI 백엔드로 트레이스가 전송되지 않으며, 그렇게 하려면 해당 작업을 수행하는 `TracingProcessor` 를 포함해야 합니다.

## 외부 트레이싱 프로세서 목록

- [AgentOps](https://docs.agentops.ai/v2/usage/typescript-sdk#openai-agents-integration)
- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agents-sdk-js)
